Canon Creative 3

home *** CD-ROM | disk | FTP | other *** search

/ Canon Creative 3 / Canon Creative 3.iso / designe / DATA.Z / README25.TXT < prev next >

Wrap

Text File | 1995-06-07 | 54.6 KB | 1,230 lines

**************************************************************** README.TXT File for Microsoft ODBC 2.5 (c) Copyright Microsoft (R) Corporation, 1995. All Rights Reserved **************************************************************** ================================================================ INTRODUCTION ================================================================ This document contains release notes for Microsoft ODBC 2.5. Information in this document should be considered to be the most up-to-date of any source. ================================================================ CONTENTS ================================================================ This document contains the following information: Section Description ======= =========== 1 Configuration Information ODBC 2.5 Installation System Requirements RISC Platforms Not Supported Components 32-Bit Multithreaded Drivers on Windows 95 ODBC Driver's Base Address Language Library File Header Files 3D Controls ODBC.INF File 2 Installation Changes Uninstall Component Usage Count Tracking File Usage Count Tracking ODBC Installation Scenarios Fresh Install Scenario Uninstall Scenario Upgrade/Replace Scenario Installer Registration Control Panel Changes System DSNs Administrator/Control Panel Setup System DSN Setup Using Functions New Installer Functions ConfigDriver SQLConfigDriver SQLInstallTranslator SQLRemoveDriver SQLRemoveDriverManager SQLRemoveTranslator Modified Installer Functions SQLConfigDataSource SQLCreateDataSource SQLGetPrivateProfileString SQLInstallDriver SQLInstallDriverManager SQLInstallODBC SQLManageDataSources SQLWritePrivateProfileString 3 ODBC Function Changes Rebinding with SQLBindCol Attempting to Add Truncated Data with SQLSetPos pcbValue in SQLBindParameter SQLSTATE S1C00 Returned By SQLPrepare SQLSTATE 22005 RETURNED BY SQLExtendedFetch and SQLFetch SQLSTATE 22008 RETURNED BY SQLExtendedFetch and SQLFetch SQLSTATE 22012 RETURNED BY SQLGetData Cursor Concurrency Set in SQLSetStmtOption Error Message Format Notes to Driver Writers ================================================================ SECTION 1: CONFIGURATION INFORMATION ================================================================ +++++++++++++++ODBC 2.5 INSTALLATION+++++++++++++++ If ODBC 2.5 components are being installed on an x86 platform over MSDN, the version 2.5 components should replace the corresponding ODBC 2.10 components. A new RELNOTES.HLP file for ODBC 2.5 will replace this version 2.10 release notes help file, and should be consulted for all ODBC 2.5 release notes. The ODBC 2.5 files should be copied from the subdirectories of \ODBC210B\X86\ODBC25 on MSDN, to the appropriate directories on your computer, replacing the corresponding version 2.10 files. Header files should be copied to the \ODBCSDK\INCLUDE directory. Library files should be copied to the \ODBCSDK\INCLUDE directory. Redistributable files should be copied to both the \ODBCSDK\REDIST32 and \WINDOWS\SYSTEM (or \SYSTEM32) directories. If you are going to use ODBC Test, the 32-bit ODBC Test file (ODBCTE32.EXE) should also be copied. +++++++++++++++SYSTEM REQUIREMENTS+++++++++++++++ ODBC 2.5 is supported on Microsoft Windows 95 and Windows NT 3.5 and 3.51. ODBC 2.5 does not have 16-bit components. Use ODBC 2.10 for 16-bit applications. +++++++++++++++RISC PLATFORMS NOT SUPPORTED+++++++++++++++ ODBC 2.5 will not be supported on RISC platforms. Use ODBC 2.10 on RISC platforms. +++++++++++++++COMPONENTS+++++++++++++++ ODBC 2.5 consists of the following components: Component Filename Driver Manager ODBC32.DLL Installer ODBCCP32.DLL ODBCCP32.CPL Cursor Library ODBCCR32.DLL Language Library ODBCINT.DLL Administrator ODBCAD32.EXE Thunking Files DS32GT.DLL ODBC16GT.DLL ODBC32GT.DLL Installer Help ODBCINST.HLP ODBCINST.CNT Header Files ODBCINST.H SQL.H SQLEXT.H SQLTYPES.H Lib Files ODBC32.LIB ODBCCP32.LIB ODBC 2.5 also uses the following thunking file that was included in the ODBC 2.10 SDK. It is not included in the ODBC 2.5 file list, so should be retained from the ODBC 2.10 SDK. Thunking File DS16GT.DLL +++++++++++32-BIT MULTITHREADED DRIVERS ON WINDOWS 95+++++++++++ On Windows 95, a 32-bit multithreaded driver will not work when a 16-bit application tries to use it. A 32-bit multithreaded driver will work, on the other hand, with a 32-bit application. The restriction on 16-bit applications occurs because Windows 95 does not support multiple threads within a 16-bit process space. The options for driver writers are as follows: 1. Write a driver that is multithreaded when running in a 32-bit process space, but single-threaded when running in a 16-bit process space. This allows maximum interoperability and performance. 2. Write a multithreaded driver that does not work with 16-bit applications on Windows 95. The driver will have decreased interoperability, but will be simpler to write. A 16-bit driver can be written as well. 3. Write a single-threaded driver that works with either 16- or 32-bit applications on Windows 95. The driver will have maximum interoperability, but decreased performance. +++++++++++++++ODBC DRIVER'S BASE ADDRESS+++++++++++++++ ODBC driver should be linked with a base address of 0x04C00000. +++++++++++++++LANGUAGE LIBRARY FILES+++++++++++++++ All of the code that needs to be localized for all of the ODBC core components has been centralized into the language library, ODBCINT.DLL. This file includes all error strings and all dialog boxes. +++++++++++++++HEADER FILES+++++++++++++++ The standard and extended header files, SQL.H and SQLEXT.H, have been modified in ODBC 2.5 to align with changes in the X/Open CAE specification. All material in SQL.H that was specific to Microsoft has been moved to SQLEXT.H. The format of the file was changed so that the datatypes and return types conform to the X/Open CAE specification. All material in SQLEXT.H that has been adopted by the standard has been moved to SQL.H. If SQL.H and/or SQLEXT.H are included in driver or application code, "-DWINDOWS" should be added to the compiler command when building 16-bit drivers or applications. SQLTYPES.H has been added to provide type definition for program types in ODBC 2.5. SQLTYPES.H defines the handle environment, SQL portable types for C, transfer types for DATE, TIME, and TIMESTAMP, and bookmarks. +++++++++++++++3D CONTROLS++++++++++++++ On Windows 95, ODBC 2.5 uses the native 3D controls of Windows 95 instead of CTL3D32.DLL. All ODBC drivers must also use the native 3D controls on Windows 95, not CTL3D32.DLL. On Windows NT, the ODBC 2.5 core components will load the Unicode version of CTL3D32.DLL. +++++++++++++++ODBC.INF FILE++++++++++++++ In the Driver Specification Section of the ODBC.INF file, the WinSysNTnn and WinSys95nn keywords (where nn is a number from 00 to 99) indicate that the files specified will be installed on either Windows NT or Windows 95, but not on both. These keywords allow developers to install files selectively. A file can have the same name, but a different binary, for Windows NT and Windows 95. ================================================================ SECTION 2: INSTALLATION CHANGES ================================================================ +++++++++++++++UNINSTALL+++++++++++++++ In the course of installing an application, a user can install ODBC components, then uninstall the ODBC components. If the ODBC files are not used by another application, then the files are deleted. If the files are used by another application, the registry entries for ODBC are changed, but the actual files are not deleted. ODBC components are uninstalled by component, not by file. The ODBC components that can be uninstalled are the ODBC core components, ODBC drivers, and ODBC translators. Any component can be uninstalled, while the other components are left installed. For example, you can uninstall the ODBC translators while leaving the core components and drivers installed. ODBC core components (which include the Driver Manager, Cursor Library, Installer, Language Library, Administrator, thunking files, etc.) are uninstalled as a whole. ODBC drivers and translators, on the other hand, are installed driver by driver, or translator by translator. Any number of ODBC drivers or translators can be uninstalled, while other drivers and translators are left installed. The Uninstall process depends upon two types of registry entries: a component usage count kept by the ODBC installer functions, and file count tracking kept by application setup programs. These registry entries are described below. +++++++++++++++COMPONENT USAGE COUNT TRACKING+++++++++++++++ The ODBC installer functions change registry and configuration information. With the exception of SQLInstallODBC (see the SQLInstallODBC section below), they do not copy and delete files. The application setup program is responsible for copying and deleting files. ODBC installer functions maintain in the registry a count of the number of times that an ODBC component has been installed. This count is kept for each of the three ODBC components: the core components, the ODBC translators, and the ODBC drivers. A separate component usage count is kept for each ODBC translator and driver installed. Each time an ODBC component is installed, an installation function is called, and the component usage count is incremented. The installation functions are SQLInstallDriverManager, SQLInstallDriver, and SQLInstallTranslator. Each time an ODBC component is uninstalled, a removal function is called, and the component usage count is decremented. The removal functions are SQLRemoveDriverManager, SQLRemoveDriver, and SQLRemoveTranslator. When an ODBC installer function is called to install an ODBC component for the first time, the function creates the registry entry and increments the component usage count, but does not copy the files. The application setup program must do that. When the installer function is called to install an ODBC component that has already been installed, it again increments the component usage count. When an ODBC installer function is called by the application to uninstall a component, and the usage count reaches 0, the installer function deletes the registry entry for that component. It does not, however, delete the component files. The application is responsible for deleting the files, and must use the file usage count to determine if the deletion should be performed (see the File Usage Count Tracking section following this section). The component usage count is kept in the following registry entry: Registry Subtree: HKEY_LOCAL_MACHINE Registry Hive: SOFTWARE Subtree: ODBC Class Name: <NO CLASS> Value Data Type: REG_DWORD Value Name: UsageCount Value Data: <Number of times this component was installed> The Key Name, which identifies the location of the component usage count value, is specified in the following table: Component Key Name (Registry Location) ODBC Core Components SOFTWARE\ODBC\ODBCINST.INI\ODBC Core ODBC Translators SOFTWARE\ODBC\ODBCINST.INI\<Translator Name> ODBC Drivers SOFTWARE\ODBC\ODBCINST.INI\<Driver Name> +++++++++++++++FILE USAGE COUNT TRACKING+++++++++++++++ The files associated with each ODBC component are not copied or deleted by the ODBC installer functions. These functions manipulate the registry entries for the components. The files are installed or deleted by the application setup program. It is also the responsibility of the setup program to create, change, and delete registry entries, as necessary, for all ODBC files it installs or deletes. The registry entry includes a file usage count that is the number of times that a file has been installed. When an application's setup program is called to uninstall a component, it should call the appropriate removal function (SQLRemoveDriverManager, SQLRemoveDriver, or SQLRemoveTranslator), which will decrement the component usage count. The setup program should then decrement the file usage count. If the file usage count reaches 0, the setup program should delete the file. If the file usage count does not reach 0, the file should not be deleted. +++++++++++++++ODBC INSTALLATION SCENARIOS+++++++++++++++ The ODBC installation functions are called according to one of three installation scenarios: fresh install, uninstall, or upgrade/replace. +++++++++++++++FRESH INSTALL SCENARIO+++++++++++++++ When a fresh install is performed, the ODBC components have not previously been installed. ODBC installation functions are called in the following sequence, and the setup program must perform the following actions. Additional information on the ODBC installer functions is provided in later sections of these release notes. 1. SQLInstallDriverManager is called to return the path for ODBC core components and increment the component usage count. The application setup program then installs the core component files. If a newer version of a core component file has not been previously installed, the application setup program copies the file, and creates the file usage count. If a newer version of a file has previously been installed, the setup program increments the file usage count. 2. SQLInstallDriver is called for each driver to add information about the driver to the ODBCINST.INI section of the registry, return the path for the driver, and increment the driver usage count. The application setup program then installs the driver files. If a newer version of a driver file has not been previously installed, the application setup program copies the file, and creates the file usage count. If a newer version of a file has previously been installed, the setup program increments the file usage count. 3. SQLConfigDriver (a new function) is called with the ODBC_INSTALL_DRIVER fOption to call the driver setup DLL. The driver setup DLL calls the ConfigDriver function to set configuration for the driver. (The application setup program must have installed the driver files, if necessary, before this step can be performed.) 4. SQLInstallTranslator (a new function) is called to add information about the translator to the ODBCINST.INI section of the registry, and increment the translator's component usage count. The application setup program then installs the translator files. If a newer version of a translator file has not been previously installed, the application setup program copies the file, and creates the file usage count. If a newer version of a file has previously been installed, the setup program increments the file usage count. +++++++++++++++UNINSTALL SCENARIO+++++++++++++++ When an application setup program is called to perform an Uninstall, the ODBC component has previously been installed by the application. ODBC installation functions are called in the following sequence, and the setup program must perform the following actions. Additional information on the ODBC installer functions is provided in later sections of these release notes. 1. SQLRemoveTranslator is called to remove information about the translator from the ODBCINST.INI section of the registry, and decrement the translator's component usage count. If the component usage count falls to 0, the function removes the translator information (including the usage count) from the registry. For each translator file, the application setup program should check the file usage count. If the file usage count has fallen to 0, the setup program should delete the file. 2. SQLRemoveDriver is called to remove information about the driver from the ODBCINST.INI section of the registry and decrement the driver usage count. If the component usage count falls to 0, the function removes the driver information (including the component usage count) from the registry, and calls SQLConfigDriver with the ODBC_REMOVE_DRIVER fOption. SQLConfigDriver calls the ConfigDriver function, which modifies the configuration as necessary. For each driver file, the application setup program should check the file usage count. If the file usage count has fallen to 0, the setup program should delete the file. 3. SQLRemoveDriverManager is called to decrement the Driver Manager component usage count. If the component usage count falls to 0, the function removes the Driver Manager information (including the usage count) from the registry. For each core component file, the application setup program should check the file usage count. If the file usage count has fallen to 0, the setup program should delete the file. +++++++++++++++UPGRADE/REPLACE SCENARIO+++++++++++++++ When a component is upgraded or replaced, the component should be removed before being reinstalled, so that the component usage count is valid. All steps in the Uninstall scenario (SQLRemoveTranslator, SQLConfigDriver, SQLRemoveDriver, and SQLRemoveDriverManager) should be performed, then all steps in the Fresh Install scenario (SQLInstallDriverManager, SQLInstallDriver, SQLConfigDriver, and SQLInstallTranslator) should be performed. (See the Fresh Install Scenario and Uninstall Scenario sections for more information.) +++++++++++++++INSTALLER REGISTRATION+++++++++++++++ The ODBC installer in ODBC 2.5 is registered by copying the ODBCCP32.CPL file to the system directory. This action loads the control panel device. The ODBC installer no longer modifies the MMCPL entry in the registry and the CONTROL.INI file directly. When run, the ODBCCP32.CPL control panel device deletes any existing ODBC entry in the MMCPL registry key. +++++++++++++++CONTROL PANEL CHANGES+++++++++++++++ The Add and Delete buttons have been removed from the Drivers dialog box that is displayed when the ODBC icon in the Control Panel (or Administrator) is chosen, then the Drivers button in the Data Sources dialog box is chosen. The buttons were removed because this program has not yet been redesigned to modify the registry or remove files properly. A System DSN button has been added to the Data Source dialog box. For information on this change, see the following System DSNs section. +++++++++++++++SYSTEM DSNs++++++++++++++ ODBC 2.5 supports the creation of a system data-source name (DSN). A data source set up with a system DSN can be used by more than one user on the same machine. It can also be used by a system-wide service, which can then gain access to the data source even if no user is logged onto the machine. A system DSN is registered in the HKEY_LOCAL_MACHINE registry, rather than the HKEY_CURRENT_USER registry. It is not tied to one user who logs on with their particular user name and password, but can be used by any user of that machine, or by an automatic system-wide service. The system DSN is, however, tied to one machine. It does not support the capability of using remote DSNs between machines. System DSNs will be registered in the following registry location: Registry Subtree: HKEY_LOCAL_MACHINE Registry Hive: SOFTWARE Subtree: ODBC Key: ODBC.INI DSNs created for individual users, i.e., registered in the HKEY_CURRENT_USER registry, as at present, will be called user DSNs, to distinguish them from system DSNs. System DSNs can be set up through the installer user interface or API functions, as described below. +++++++++++++++ADMINISTRATOR/CONTROL PANEL SETUP++++++++++++++ A System DSN button has been added to the Data Sources dialog box displayed when the ODBC Administrator icon in the ODBC group is chosen, or when the ODBC icon in the Control Panel is chosen. When the System DSN button is chosen, a System Data Sources dialog box is displayed with controls that allow you to add or delete a system data source to your local computer, or to set the configuration for a system data source. +++++++++++++++SYSTEM DSN SETUP USING FUNCTIONS++++++++++++++ Five ODBC installer functions have been modified to accommodate system DSNs. Applications can call these functions in order to implement automatic or customized interactive management of system DSNs. SQLConfigDataSources has been changed to accommodate the addition, configuration, and removal of system DSNs. SQLCreateDataSource has been changed to add a System DSN check box to the Add Data Source dialog box. SQLManageDataSources has been changed to accommodate the System DSN button in the Data Sources dialog box. SQLGetPrivateProfileString and SQLWritePrivateProfileString support configuration of system DSNs for existing drivers. The system DSN works only if a driver reads from the registry using SQLGetPrivateProfileString and writes to the registry using SQLWritePrivateProfileString. If a driver reads from, or writes to, the registry itself, the system DSN may not work. +++++++++++++++NEW INSTALLER FUNCTIONS+++++++++++++++ The following new installer and driver setup functions have been added in ODBC 2.5 to support Uninstall and System DSNs. The functions are described in the Uninstall and System DSN sections above, and in detail below. ConfigDriver SQLConfigDriver SQLInstallTranslator SQLRemoveDriver SQLRemoveDriverManager SQLRemoveTranslator +++++++++++++++ConfigDriver+++++++++++++++ Purpose: ConfigDriver allows a driver to perform install and uninstall functions without requiring an application to call ConfigDSN. This function will perform driver-specific functions such as creating driver-specific INI files and performing DSN conversions during installation, and cleaning up INI files or registry modifications during Uninstall. This function is exposed by the driver setup DLL. Syntax: BOOL ConfigDriver (hwndParent, fRequest, lpszDriver, lpszArgs, lpszMsg, cbMsgMax, pcbMsgOut) Type Argument Use Description HWND hwndParent Input Parent window handle. WORD fRequest Input Type of request. fRequest must contain one of the following values: ODBC_INSTALL_DRIVER: installing a new driver ODBC_REMOVE_DRIVER: removing a driver This option can also be driver-specific, in which case the first option will be ODBC_CONFIG_DRIVER_MAX+1, and additional options will be incremented by 1 from that value. LPCSTR lpszDriver Input The name of the driver as registered in the ODBCINST.INI key of the registry. LPCSTR lpszArgs Input A null-terminated string containing arguments for a driver-specific fRequest. LPSTR lpszMsg Output A null-terminated string containing an output message from the driver setup. WORD cbMsgMax Input Length of lpszMsg. WORD pcbMsgOut Output Total number of bytes FAR * available to return in lpszMsg. If the number of bytes available to return is greater than or equal to cbMsgMax, the output message in lpszMsg is truncated to cbMsgMax-1 characters. Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. Comments: All drivers that make modifications at the time ConfigDriver is called with the ODBC_INSTALL_DRIVER option should properly delete or uninstall those modifications when ConfigDriver is called with the ODBC_REMOVE_DRIVER option. Driver-Specific Options: An application can request driver- specific features exposed by the driver by using the fRequest argument. The fRequest for the first option will be ODBC_CONFIG_DRIVER_MAX+1, and additional options will be incremented by 1 from that value. Any arguments required by the driver for that function should be provided in a null-terminated string passed in the lpszArgs argument. Drivers providing such functionality should maintain a table of driver-specific options. The options should be fully documented in driver documentation. Application writers who make use of driver-specific options should be aware that this use will make the application less interoperable. Messages: A driver setup routine can send a text message to an application as null-terminated strings in the lpszMsg buffer. The message will be truncated to cbMsgMax-1 characters by the ConfigDriver function if it is greater than or equal to cbMsgMax characters. +++++++++++++++SQLConfigDriver+++++++++++++++ Purpose: SQLConfigDriver loads the appropriate driver setup DLL and calls the ConfigDriver function. Syntax: BOOL SQLConfigDriver (hwndParent, fRequest, lpszDriver, lpszArgs, lpszMsg, cbMsgMax, pcbMsgOut) Type Argument Use Description HWND hwndParent Input Parent window handle. WORD fRequest Input Type of request. fRequest must contain one of the following values: ODBC_INSTALL_DRIVER: installing a new driver ODBC_REMOVE_DRIVER: removing a driver This option can also be driver-specific, in which case the first option will be ODBC_CONFIG_DRIVER_MAX+1, and additional options will be incremented by 1 from that value. LPCSTR lpszDriver Input The name of the driver as registered in the ODBCINST.INI key of the registry. LPCSTR lpszArgs Input A null-terminated string containing arguments for a driver-specific fRequest. LPSTR lpszMsg Output A null-terminated string containing an output message from the driver setup. WORD cbMsgMax Input Length of lpszMsg. WORD pcbMsgOut Output Total number of bytes FAR * available to return in lpszMsg. If the number of bytes available to return is greater than or equal to cbMsgMax, the output message in lpszMsg is truncated to cbMsgMax-1. Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. Comments: SQLConfigDriver allows an application to call a driverÆs ConfigDriver routine without having to know the name and load the driver-specific setup DLL. A setup program calls this function after the driver setup DLL has been installed. The calling program should be aware that this function may not be available for all drivers. In such a case, the calling program should continue without error. Driver-Specific Options: An application can request driver- specific features exposed by the driver by using the fRequest argument. The fRequest for the first option will be ODBC_CONFIG_DRIVER_MAX+1, and additional options will be incremented by 1 from that value. Any arguments required by the driver for that function should be provided in a null-terminated string passed in the lpszArgs argument. Drivers providing such functionality should maintain a table of driver-specific options. The options should be fully documented in driver documentation. Application writers who make use of driver-specific options should be aware that this use will make the application less interoperable. Messages: A driver setup routine can send a text message to an application as null-terminated strings in the lpszMsg buffer. The message will be truncated to cbMsgMax-1 characters by the ConfigDriver function if it is greater than or equal to cbMsgMax characters. +++++++++++++++SQLInstallTranslator+++++++++++++++ Purpose: SQLInstallTranslator adds information about a translator to the ODBCINST.INI section of the registry and increments the translatorÆs UsageCount by 1. Syntax: BOOL SQLInstallTranslator (lpszInfFile, lpszTranslator, lpszPathIn, lpszPathOut, cbPathOutMax, pcbPathOut, fRequest, lpdwUsageCount) Type Argument Use Description LPCSTR lpszInfFile Input Full path of the ODBC.INF file or a null pointer. If lpszInfFile is a null pointer, lpszTranslator must contain a list of keyword-value pairs describing the translator. LPCSTR lpszTranslator Input If lpszInfFile is the path of the ODBC.INF file, this must be the key in the ODBC.INF file that describes the translator. If lpszInfFile is a null pointer, this must contain a list of keyword-value pairs describing the translator. The Translator and Setup keywords have to be included in the lpszTranslator string. The translation DLL is listed with the Translator keyword, and the translator setup DLL is listed with the Setup keyword. LPCSTR lpszPathIn Input Full path of where the translator is to be installed or a null pointer. If lpszPath is a null pointer, then the translators will be installed in the System directory. LPSTR lpszPathOut Output The path of where the translator should be installed. If the translator has never been installed, then lpszPathOut is the same as lpszPathIn. If there exists a prior installation of the translator, then lpszPathOut is the path of the prior installation. WORD cbPathOutMax Input Length of lpszPathOut. WORD pcbPathOut Output Total number of bytes FAR * available to return in lpszPathOut. If the number of bytes available to return is greater than or equal to cbPathOutMax, the output path in lpszPathOut is truncated to pcbPathOutMax-1 characters. WORD fRequest Input Type of request. fRequest must contain one of the following values: ODBC_INSTALL_INQUIRY: inquire about where a translator can be installed ODBC_INSTALL_COMPLETE: complete the installation request LPDWORD lpdwUsageCount Output The usage count of the translator after this function has been called. Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. Comments: SQLInstallTranslator provides a mechanism to install just the translator. This function does not actually copy any files. The calling program is responsible for copying the translator files. If a version of the translator already exists, but the UsageCount value for the translator does not exist, the new UsageCount value is set to 2. Length of the Path in lpszPathOut: SQLInstallTranslator allows for a two-phase install process, so an application can determine what cbPathOutMax should be by calling SQLInstallTranslator with an fRequest of ODBC_INSTALL_INQUIRY mode. This will return the total number of bytes available in the pcbPathOut buffer. SQLInstallTranslator can then be called with an fRequest of ODBC_INSTALL_COMPLETE and the cbPathOutMax argument set to the value in the pcbPathOut buffer, plus 1. If you choose not to use the two-phase model for SQLInstallTranslator, then you must set cbPathOutMax to the value _MAX_PATH, as defined in STDLIB.H, to prevent truncation. When fRequest is ODBC_INSTALL_COMPLETE, SQLInstallTranslator does not allow lpszPathOut to be NULL (or cbPathOutMax to be 0). If fRequest is ODBC_INSTALL_COMPLETE, FALSE is returned when the number of bytes available to return is greater than or equal to cbPathOutMax, with the result that truncation occurs. +++++++++++++++SQLRemoveDriver+++++++++++++++ Purpose: SQLRemoveDriver removes information about the driver from the ODBCINST.INI registry entry. Syntax: BOOL SQLRemoveDriver (lpszDriver, fRemoveDSN, lpdwUsageCount) Type Argument Use Description LPCSTR lpszDriver Input The name of the driver as registered in the ODBCINST.INI key of the registry. BOOL fRemoveDSN Input The valid values are: TRUE Remove DSNs associated with the driver specified in lpszDriver. FALSE Do not remove DSNs associated with the driver specified in lpszDriver. LPDWORD lpdwUsageCount Output The usage count of the driver after this function has been called. Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE. Comments: SQLRemoveDriver complements the SQLInstallDriver function, and updates the UsageCount. This function does not actually remove any files. The calling program is responsible for deleting files. SQLRemoveDriver will decrement the UsageCount value by 1. If the UsageCount goes to 0, then the following will occur: 1. SQLConfigDriver with the ODBC_REMOVE_DRIVER option will be called. If the fRemoveDSN option is set to TRUE, the ConfigDSN function calls SQLRemoveDSNFromIni to remove all the data associated with the driver specified in lpszDriver. 2. The driver registry entry itself will be removed. +++++++++++++++SQLRemoveDriverManager+++++++++++++++ Purpose: SQLRemoveDriverManager removes information about the ODBC core components from the ODBCINST.INI registry entry. Syntax: BOOL SQLRemoveDriverManager (lpdwUsageCount) Type Argument Use Description LPDWORD lpdwUsageCount Output The usage count of the Driver Manager after this function has been called. Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE. Comments: SQLRemoveDriverManager complements the SQLInstallDriverManager function, and updates the UsageCount. This function does not remove any files. The calling program is responsible for deleting files. SQLRemoveDriverManager will decrement the UsageCount value of the ODBC core components by 1. If the UsageCount goes to 0, then the ODBC core component registry entry will be removed. +++++++++++++++SQLRemoveTranslator+++++++++++++++ Purpose: SQLRemoveTranslator removes information about a translator from the ODBCINST.INI section of the registry and decrements the translatorÆs UsageCount by 1. Syntax: BOOL SQLRemoveTranslator (lpszTranslator, lpdwUsageCount) Type Argument Use Description LPCSTR lpszTranslator Input The name of the translator as registered in the ODBCINST.INI key of the registry. LPDWORD lpdwUsageCount Output The usage count of the translator after this function has been called. Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE. Comments: If the UsageCount goes to 0, then the translatorÆs registry entry will be removed. This function does not remove any files. The calling program is responsible for properly removing the translator files. +++++++++++++++MODIFIED INSTALLER FUNCTIONS+++++++++++++++ The following installer functions have been modified in ODBC 2.5 to support Uninstall and System DSNs. To support full backward compatibility, unless otherwise specified, all of the modified APIs will support all existing functionality. The functions are described in the Uninstall and System DSN sections above, and in detail below. SQLConfigDataSource SQLCreateDataSource SQLGetPrivateProfileString SQLInstallDriver SQLInstallDriverManager SQLInstallODBC SQLManageDataSources SQLWritePrivateProfileString +++++++++++++++SQLConfigDataSource+++++++++++++++ SQLConfigDataSource provides the same functionality as in the ODBC 2.10 installer, with the addition of the following SystemDSN options in the fRequest argument: ODBC_ADD_SYS_DSN, ODBC_CONFIG_SYS_DSN, and ODBC_REMOVE_SYS_DSN. These options are added to enable adding, removing, or changing the configuration of a System DSN. The fRequest argument is now as follows: Type Argument Use Description HWND hwndParent Input Parent window handle. The function will not display any dialog boxes if the handle is null. WORD fRequest Input Type of request. fRequest must contain one of the following values: ODBC_ADD_DSN: Add new user data source. ODBC_CONFIG_DSN: Modify an existing data source. ODBC_REMOVE_DSN: Remove an existing data source. ODBC_ADD_SYS_DSN: Add a new system data source. ODBC_CONFIG_SYS_DSN: Modify an existing system data source. ODBC_REMOVE_SYS_DSN: Remove an existing system data source. LPCSTR lpszDriver Input Driver description (usually the name of the associated DBMS) presented to users instead of the physical driver name. LPCSTR lpszAttributes Input List of attributes in the form of keyword-value pairs. For more information, see ConfigDSN in the Microsoft ODBC 2.10 Programmer's Reference. Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE. SQLConfigDataSource maps the system DSN fRequests to the user DSN fRequests (ODBC_ADD_SYS_DSN to ODBC_ADD_DSN, ODBC_CONFIG_SYS_DSN to ODBC_CONFIG_DSN, and ODBC_REMOVE_SYS_DSN to ODBC_REMOVE_DSN). To distinguish user and system DSNs, SQLConfigDataSource sets the wSystemDSN state variable according to the following table. Prior to returning, SQLConfigDataSource resets wSystemDSN to BOTHDSN. fRequest wSystemDSN ODBC_ADD_DSN USERDSN_ONLY ODBC_CONFIG_DSN USERDSN_ONLY ODBC_REMOVE_DSN USERDSN_ONLY ODBC_ADD_SYS_DSN SYSTEMDSN_ONLY ODBC_CONFIG_SYS_DSN SYSTEMDSN_ONLY ODBC_REMOVE_SYS_DSN SYSTEMDSN_ONLY +++++++++++++++SQLCreateDataSource+++++++++++++++ SQLCreateDataSource provides the same functionality as in the ODBC 2.10 installer, with the addition of a System DSN check box in the Add Data Source dialog box. This check box allows the user to specify whether a user DSN or a system DSN should be created. If a driver is chosen with the System DSN check box selected, SQLCreateDataSource sets the wSystemDSN flag to SYSTEMDSN_ONLY, and calls ConfigDSN in the driver setup DLL with an fRequest of ODBC_ADD_DSN. The System DSN check box is displayed whenever the SQLCreateDataSource function is called to display the Add Data Source dialog box, except when this dialog box is displayed through the Control Panel. In this case, a data source is added either from the Data Sources dialog box (for user data sources) or from the System Data Sources dialog box, so the System DSN check box is not needed. +++++++++++++++SQLGetPrivateProfileString+++++++++++++++ This function gets a list of DSN values from the ODBC.INI entry in the registry. A wSystemDSN state variable indicates where the registry entry is. If the DSN is a User DSN (the state variable is USERDSN_ONLY), the function reads from the ODBC.INI entry in HKEY_CURRENT_USER. If the DSN is a system DSN (SYSTEMDSN_ONLY), the ODBC.INI entry in HKEY_LOCAL_MACHINE is used. If the state variable is BOTHDSN, HKEY_CURRENT_USER is tried, and if it fails, then HKEY_LOCAL_MACHINE is used. +++++++++++++++SQLInstallDriver+++++++++++++++ This function will perform the same functionality as listed in the ODBC 2.10 ProgrammerÆs Reference. It will also increment the UsageCount for the installed driver by 1. However, if a version of the driver already exists, but the UsageCount value for the driver does not exist, the new UsageCount value is set to 2. +++++++++++++++SQLInstallDriverManager+++++++++++++++ This function will perform the same functionality as listed in the ODBC 2.10 ProgrammerÆs Reference. It will also increment the UsageCount for the ODBC core components by 1. However, if a version of the Driver Manager already exists, but the UsageCount value for the core components does not exist, the new UsageCount value is set to 2. +++++++++++++++SQLInstallODBC+++++++++++++++ In addition to performing the same functions it currently does, as described in the ODBC 2.10 Programmer's Reference, this function will also perform the following: 1. Increment the component usage count of the ODBC core components. 2. Increment the component usage count of the drivers being installed. 3. Increment the component usage count of the translators being installed. 4. Increment the file usage count of each file being installed. 5. Modify the FileList key with the appropriate files (see the File Count Tracking section of this readme for more information). Note that SQLInstallODBC is the only one of the ODBC installer functions that actually copies files. SQLInstallODBC does not support the Uninstall process. If an application's setup program uses SQLInstallODBC, the application will not be Windows 95 logo compliant. SQLInstallODBC performs the same functions as SQLInstallDriverManager, SQLInstallDriver, SQLConfigDriver (with ODBC_INSTALL_DRIVER), and SQLInstallTranslator. SQLInstallODBC does not perform the functions accomplished by SQLRemoveTranslator, SQLConfigDriver (with SQL_REMOVE_DRIVER), SQLRemoveDriver, and SQLRemoveDriverManager). SQLInstallODBC should incorporate the removal functions, and so support Uninstall and Windows 95 logo compliance, in ODBC 3.0. +++++++++++++++SQLManageDataSources+++++++++++++++ SQLManageDataSources has been changed to accommodate the user interface changes necessary to support system DSNs (see the Administrator/Control Panel Setup section). The function provides the same functionality as in the ODBC 2.10 installer, with the addition of the SystemDSN button. +++++++++++++++SQLWritePrivateProfileString+++++++++++++++ This function writes DSN information to the ODBC.INI entry in the registry. A wSystemDSN state variable indicates where the registry entry is. If the DSN is a User DSN (the state variable is USERDSN_ONLY), the function writes to the ODBC.INI entry in HKEY_CURRENT_USER. If the DSN is a system DSN (SYSTEMDSN_ONLY), the ODBC.INI entry in HKEY_LOCAL_MACHINE is used. If the state variable is BOTHDSN, HKEY_CURRENT_USER is used. ================================================================ SECTION 3: ODBC FUNCTION CHANGES ================================================================ The following changes have been made to the ODBC functions documented in the ODBC 2.10 Programmer's Reference and SDK Guide. +++++++++++++++REBINDING WITH SQLBindCol+++++++++++++++ An application can call SQLBindCol to bind a column to a new storage location, regardless of whether data has already been fetched. The new binding replaces the old binding. This is true for bookmark columns as well as other bound columns. Note that the new binding does not apply to data already fetched--it takes effect the next time SQLFetch, SQLExtendedFetch, or SQLSetPos is called. +++++++ATTEMPTING TO ADD TRUNCATED DATA WITH SQLSetPos+++++++ Using SQLSetPos with an fOption of SQL_ADD to add data from a buffer that was truncated when bound by a call to SQLBindCol, will result in a General-Protection Fault. Prior to calling SQLSetPos with an fOption of SQL_ADD, application writers should verify that the value pointed to by pcbValue in the accompanying call to SQLBindCol is not greater than cbValueMax. +++++++++++++++pcbValue IN SQLBindParameter+++++++++++++++ When pcbValue in SQLBindParameter is SQL_DEFAULT_PARAM, the corresponding parameter can only be a parameter for an ODBC canonical procedure invocation. SQLExecDirect, SQLExecute, and SQLPutData return SQLSTATE 07S01 (Invalid use of default parameter) when a parameter value was set to SQL_DEFAULT_PARAM, and the corresponding parameter was not a parameter for an ODBC canonical procedure invocation. +++++++++++++SQLSTATE S1C00 RETURNED BY SQLPrepare+++++++++++++ SQLPrepare will return SQLSTATE S1C00 (Driver not capable) if the cursor/concurrency combination is invalid. +++SQLSTATE 22005 RETURNED BY SQLExtendedFetch and SQLFetch+++ SQLExtendedFetch and SQLFetch will return SQLSTATE 22005 (Error in assignment) if a zero-length string was inserted into a string field, and the field was bound to a numeric data type, so the string was converted to a zero. +++SQLSTATE 22008 RETURNED BY SQLExtendedFetch and SQLFetch+++ SQLExtendedFetch and SQLFetch will return SQLSTATE 22008 (Datetime field overflow) if a SQL_C_TIME, SQL_C_DATE, or SQL_C_TIMESTAMP value was converted to a SQL_CHAR data type, and the value was, respectively, an invalid date, time, or timestamp. ++++++++++++SQLSTATE 22012 RETURNED BY SQLGetData++++++++++++ SQLGetData will return SQLSTATE 22012 (Division by zero) if a value from an arithmetic expression was returned that resulted in division by zero. +++++++++++CURSOR CONCURRENCY SET IN SQLSetStmtOption++++++++++ The default value for SQL_CONCURRENCY is SQL_CONCUR_READ_ONLY. This option can also be set through the fConcurrency argument in SQLSetScrollOptions. This option cannot be specified for an open cursor. If the SQL_CURSOR_TYPE fOption is changed to a type that does not support the current value of SQL_CONCURRENCY, the value of SQL_CONCURRENCY is not automatically changed to a supported value, and no error will be reported until SQLExecDirect or SQLPrepare is called. If the driver supports the SELECT_FOR_UPDATE statement, and such a statement is executed while the value of SQL_CONCURRENCY is set to SQL_CONCUR_READ_ONLY, an error will be returned. If the value of SQL_CONCURRENCY is changed to a value that the driver supports for some value of SQL_CURSOR_TYPE, but not for the current value of SQL_CURSOR_TYPE, the value of SQL_CURSOR_TYPE is not automatically changed to a supported value, and no error will be reported until SQLExecDirect or SQLPrepare is called. ++++++++++++++ERROR MESSAGE FORMAT+++++++++++++ Error messages returned by the Driver Manager have the following format: [Microsoft][ODBC Driver Manager] message-text. The old format was: [Microsoft][ODBC DLL] message-text. ++++++++++++++NOTES TO DRIVER WRITERS+++++++++++++ 1. As described in the ODBC 2.0 Programmer's Reference, the ODBC 2.0 Driver Manager uses ordinal number 199 to determine whether or not to load functions by ordinal or by name. If a driver does not define its functions in the ordinal order defined by ODBC, it MUST not define ordinal number 199. Note that by default, the Microsoft C/C++ compiler defines ordinal values for all far functions, not only exported functions. This can cause ordinal 199 to be defined even if there is no function explicitly mapped to that ordinal. To make sure the compiler doesn't assign ordinal values for non-exported functions, include the "PROTMODE" statement in the definition (.DEF) file that describes the dynamic-link library. For more information, see "Building Drivers: Use of PROTMODE Line in .DEF Files" in the ODBC SDK Knowledge Base Help file. 2. An application might occasionally invoke a driver connection while responding to a DDE Initiate request from another application. If the driver displays a connect dialog box and yields to Windows, it may cause unpredictable system behavior. Therefore, drivers must call InSendMessage before displaying any dialog or message boxes to see if they are being called while the application is in SendMessage processing. If so, only SYSTEM MODAL dialogs are permitted so that Windows can block additional messages being sent to the applications. Drivers that support the asynchronous mode of ODBC operations MUST not rely upon windows PeekMessage functionality to emulate such support. This also applies to ALL underlying components (network libraries, any asynchronous DDEML based drivers, underlying data access components, and so on). Any ODBC application that implements asynchronous ODBC operations may show unexpected behavior and cause the entire Windows system to become unstable, if such a driver was used. Therefore, driver writers must make sure that implementation of asynchronous mode does not yield control to Windows. 3. For driver-specific options (>999), the thunking layer checks to see if vParam is a valid pointer. If it is not, vParam is passed unchanged as a 32-bit integer. In the case where an application expects vParam to be an integer, and the value for vParam happened to be a valid pointer, the driver will receive an invalid 32-bit integer value. In addition, if a driver tries to return a pointer in the pvParam argument of SQLGetStmtOption for a driver-specific option, it will not be translated. Instead of passing back a pointer, the driver should copy the associated value back into the calling application's buffer.